home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / program / ros_v1_2.lha / ros.doc < prev    next >
Text File  |  1996-01-08  |  55KB  |  1,493 lines
  1. TABLE OF CONTENTS
  2.  
  3. ros.library/--Overview--
  4. ros.library/--History--
  5. ros.library/ROSAddTimerInt
  6. ros.library/ROSAllocAudio
  7. ros.library/ROSAllocMem
  8. ros.library/ROSAwakeSystem
  9. ros.library/ROSChipsetCheck
  10. ros.library/ROSCPUCheck
  11. ros.library/ROSCPUClock
  12. ros.library/ROSDeleteFile
  13. ros.library/ROSDisableReq
  14. ros.library/ROSEnableReq
  15. ros.library/ROSFreeAudio
  16. ros.library/ROSFreeMem
  17. ros.library/ROSGetDMA
  18. ros.library/ROSGetInt
  19. ros.library/ROSGetKey
  20. ros.library/ROSKillSystem
  21. ros.library/ROSQueryKeys
  22. ros.library/ROSReadExe
  23. ros.library/ROSReadFile
  24. ros.library/ROSRemTimerInt
  25. ros.library/ROSRequester
  26. ros.library/ROSScreenToBack
  27. ros.library/ROSScreenToFront
  28. ros.library/ROSSetCache
  29. ros.library/ROSSetCopper
  30. ros.library/ROSSetDMA
  31. ros.library/ROSSetExitHandler
  32. ros.library/ROSSetInt
  33. ros.library/ROSSetIntVec
  34. ros.library/ROSSetTimerVec
  35. ros.library/ROSStartTimer
  36. ros.library/ROSStopTimer
  37. ros.library/ROSSysCall
  38. ros.library/ROSSysCallEnd
  39. ros.library/ROSWaitVBlank
  40. ros.library/ROSWriteFile
  41.  
  42. ros.library/--Overview--                              ros.library/--Overview--
  43.  
  44. This section describes the way how to use the RETIRE Operating System within
  45. your own applications:
  46.  
  47. The ros.library is an enhanced lowlevel.library. It's compatible with currently
  48. all available machines and CPU's (upto '060) and OS1.3 compatible too!
  49. The ROS provides additional functions to take over the entire system so it
  50. should be useful for demo & game coders.
  51. Another advantage is the ability to call important system functions (memory
  52. allocation, read, write) from a killed system.
  53. ROS offers a way to run your hardware bashing application within multitasking.
  54. And finally a ROS prefs file is provided to support custom settings.
  55. On startup ROS tries to load the ROS.prefs from your ENV: directory. You may
  56. edit this file to configure the library for your needs.
  57.  
  58. But remember: It's impossible to open the ros.library from two applications at
  59. the same time. The second application will fail to open the library!
  60.  
  61. Programming guidelines:
  62.  
  63. The ros.library is a standard Amiga library so normal restrictions applies to
  64. function calls:  - a6 loaded with _ROSBase
  65.                  - d0/d1/a0/a1 scratch registers (destroyed by libcall)
  66.                  - functions can't be called from within interrupts
  67. Some ROS functions are special in these cases; they need no scratch registers
  68. or they may be called from within interrupts. Look at the appropriate 'note'
  69. comment for further information.
  70.  
  71. Do not call any ROS function from supervisor mode. The machine will crash!!!
  72. I think there is no need to switch to supervisor mode. Think of the '060 CPU;
  73. its supervisor model differs from the '040 CPU and a few basic commands will be
  74. emulated by software. Executing such a command from supervisor mode may crash
  75. the machine!!!
  76.  
  77. Call ROSKillSystem(ROSKSF_DEATHMODE) to take over the entire system. But do not
  78. modify DMA & interrupt stuff by yourself! Use the appropriate ROS routines!!!!!
  79. ROSKillSystem() opens a PAL-LowRes screen so all 'special' AGA registers are
  80. flushed (FMODE may not!?!) and it forces graphics boards to switch to the Amiga
  81. custom chip display.
  82.  
  83. After taking over the system you may use the blitter. You should finish your
  84. blits before calling ROS functions which may invoke system calls. After the
  85. function returns you may bash the blitter again.
  86. Remember: Use a WaitBlit before freeing some chip memory!!!
  87.  
  88. In a multitasking environment your vblank code may be called after the display
  89. is started depending on the speed of higher prioritized vblank interrupts.
  90. If you want to synchronize custom chip modifications with the display you
  91. should use the copper.
  92. And remember: The vblank frequency may vary (not always 50 Hz) if ROS screen
  93. behind other screens!
  94.  
  95. The registers you may trash:
  96. - the display custom chip registers after taking over the system, in multi-
  97.   tasking mode only if the ROS screen is the frontmost
  98. - the audio custom chip registers (if channels allocated)
  99. - the blitter registers (only if taken over the system)
  100. - the CIA registers (if successfully allocated)
  101.  
  102. You should never touch:
  103. - DMACON and INTENA registers
  104. - CIA ICR registers
  105. - CPU interrupt vectors
  106. - serial registers
  107. - disk related registers
  108.  
  109. Please read the following autodocs carefully!
  110. If you have questions, problems, idea's or bug reports feel free to contact me:
  111.  
  112. TIK/RETIRE via email:  Nico.Schmidt@Student.Uni-Magdeburg.de
  113.  
  114. or write to:           Nico Schmidt
  115.                        Möhlauer Str. 9
  116.                        06773 Jüdenberg
  117.                        GERMANY
  118.  
  119. Thanks to:  TODI/RETIRE for hints and useful idea's
  120.             PABLO/RETIRE for beta testing
  121.  
  122. ros.library/--History--                                ros.library/--History--
  123.  
  124.                                   ROS HISTORY
  125.  
  126. *******************************************************************************
  127. RELEASE 1.0, 29.12.95 (Library version 1.0)
  128.  
  129.     The first release.
  130.  
  131. *******************************************************************************
  132. RELEASE 1.1, 05.01.96 (Library version 1.1)
  133.  
  134.     Fixed two minor bugs:
  135.       - ROSCPUClock() shouldn't display a requester if no free CIA available,
  136.         but it does
  137.       - user vblank code was called from vblank server with priority 9, this
  138.         may confuse the timer.device (priority 0) and thus all CIA interrupts
  139.         (e.g. level6 p61) if it steals to much rastertime;
  140.         now user vblank code is executed from a priority 0 vblank server
  141.  
  142. *******************************************************************************
  143. RELEASE 1.2, 08.01.96 (Library version 1.2)
  144.  
  145.     Library name changed from 'ROS.library' to 'ros.library' because a library
  146.     name should always be a lower-case string (thanks to Thomas Kessler)
  147.  
  148. *******************************************************************************
  149.  
  150. ros.library/ROSAddTimerInt                          ros.library/ROSAddTimerInt 
  151.  
  152.    NAME
  153.         ROSAddTimerInt -- add an interrupt that is executed at regular
  154.                           intervals
  155.  
  156.    SYNOPSIS
  157.         intHandle = ROSAddTimerInt(Flags, intRoutine);
  158.         D0                         D0     A0
  159.  
  160.         ULONG AddTimerInt(ULONG, APTR);
  161.  
  162.    FUNCTION
  163.         Calling this routine causes the system to allocate a CIA timer
  164.         depending on 'Flags' and set up 'intRoutine' to service any interrupts
  165.         caused by the timer.
  166.         Although the timer is allocated it is neither running, nor enabled.
  167.         ROSStartTimer() must be called to establish the time interval and
  168.         start the timer.
  169.  
  170.         The routine is called from within an interrupt, so normal
  171.         restrictions apply. On entry A5 holds the custom base ($dff000) and
  172.         A6 holds _ROSBase. Your code may trash all registers.
  173.  
  174.         The CIA timer used by this routine is not guaranteed to always be
  175.         the same. This routine utilizes the CIA resource and uses an
  176.         unallocated CIA timer.
  177.  
  178.         You should remove the timer with ROSRemTimerInt().
  179.         Closing the ros.library removes this timer interrupt automatically.
  180.  
  181.    INPUTS
  182.         Flags - specify the timer to allocate:
  183.                         TIMF_ANY  - try to allocate any timer 
  184.                         TIMF_LEV2 - try to allocate level 2 timers (CIA A)
  185.                         TIMF_LEV6 - try to allocate level 6 timers (CIA B)
  186.         intRoutine - the routine to invoke upon timer interrupts.
  187.  
  188.    RESULT
  189.         intHandle - a handle used to manipulate the interrupt, or NULL
  190.                     if it was not possible to attach the routine.
  191.  
  192.    NOTE
  193.         If allocation failed a Retry/Cancel-Requester appears to inform the
  194.         user about the problem (if not suppressed and if not in Death-Mode).
  195.  
  196.         This function interrupts the Death-Mode state with ROSSysCall()!
  197.  
  198.    SEE ALSO
  199.         ROSRemTimerInt(), ROSStartTimer(), ROSStopTimer(), ROSSetTimerVec()
  200.  
  201. ros.library/ROSAllocAudio                            ros.library/ROSAllocAudio
  202.  
  203.    NAME
  204.         ROSAllocAudio -- allocate audio channels
  205.  
  206.    SYNOPSIS
  207.         success = ROSAllocAudio()
  208.         D0                     
  209.  
  210.         BOOL ROSAllocAudio(VOID);
  211.  
  212.    FUNCTION
  213.         This function allocates all audio channels. Audio DMA is updated
  214.         so that matches with current DMA settings (former ROSSetDMA() calls).
  215.    
  216.         You should free the audio channels with ROSFreeAudio().
  217.         Closing the ros.library frees audio channels automatically.
  218.  
  219.    RESULT
  220.         success - boolean
  221.  
  222.    NOTE
  223.         If allocation failed a Retry/Cancel-Requester appears to inform the
  224.         user about the problem (if not suppressed and if not in Death-Mode).
  225.  
  226.         This function interrupts the Death-Mode state with ROSSysCall()!
  227.  
  228.    SEE ALSO
  229.         ROSFreeAudio()
  230.  
  231. ros.library/ROSAllocMem                                ros.library/ROSAllocMem
  232.  
  233.    NAME
  234.         ROSAllocMem -- allocate memory and keep track of the size
  235.  
  236.    SYNOPSIS
  237.         memoryBlock = ROSAllocMem(byteSize, attributes, alignmask)
  238.         D0                        D0        D1          D2
  239.  
  240.         VOID *ROSAllocMem(ULONG, ULONG, ULONG);
  241.  
  242.    FUNCTION
  243.         This function works identically to Exec's AllocMem(), but tracks the
  244.         size of the allocation and provides additional memory alignment.
  245.  
  246.         See the AllocMem() documentation for details.
  247.  
  248.         You should free the memory with ROSFreeMem().
  249.         Do _not_ use exec.library functions!!!!!!!
  250.         Closing the ros.library frees allocated memory automatically.
  251.  
  252.    INPUTS
  253.         byteSize - # of bytes to allocate
  254.         attributes - memory requirements
  255.         alignmask - used to allocate memory at special boundaries, if NULL
  256.                     Exec's standard alignment applies
  257.  
  258.                     --> newaddr = memaddr AND NOT(alignmask)
  259.                     e.g. mem align: even by 8 bytes -> alignmask = $00000007
  260.  
  261.    RESULT
  262.         memoryBlock - a pointer to the newly allocated memory block or NULL
  263.  
  264.    NOTE
  265.         This function interrupts the Death-Mode state with ROSSysCall()!
  266.  
  267.    SEE ALSO
  268.         ROSFreeMem(), exec.lib/AllocMem()
  269.  
  270. ros.library/ROSAwakeSystem                          ros.library/ROSAwakeSystem
  271.  
  272.    NAME
  273.         ROSAwakeSystem -- close ROS screen and awake from Death-Mode
  274.  
  275.    SYNOPSIS
  276.         ROSAwakeSystem()
  277.  
  278.         VOID ROSAwakeSystem(VOID);
  279.  
  280.    FUNCTION
  281.         This function deallocates all things allocated with ROSKillSystem().
  282.         It closes the opened screen and sets the display related DMA to the
  283.         appropriate system values.
  284.         Calling this function without a matching ROSKillSystem() is harmless.
  285.  
  286.         Closing the ros.library calls automatically ROSAwakeSystem().
  287.  
  288.    SEE ALSO
  289.         ROSKillSystem()
  290.  
  291. ros.library/ROSChipsetCheck                        ros.library/ROSChipsetCheck
  292.  
  293.    NAME
  294.         ROSChipsetCheck -- check if desired custom chipset available
  295.  
  296.    SYNOPSIS
  297.         result = ROSChipsetCheck(chipsetbit)
  298.         D0                       D0        
  299.  
  300.         UWORD ROSChipsetCheck(UWORD);
  301.  
  302.    FUNCTION
  303.         Use this routine to obtain the available chipset.
  304.         As input you may specify the chipset requirement (bitnumber) and if
  305.         _not_ found a requester appears to inform the user about his lack of
  306.         hardware (if not suppressed and if not in Death-Mode).
  307.  
  308.    INPUTS
  309.         chipsetbit - the required chipset; currently defined are
  310.                          ROSCSB_ECS for at least HR-AGNUS rev3 and 8373 DENISE
  311.                          ROSCSB_AGA for at least ALICE rev2 and LISA,
  312.                      or -1 for only obtaining chipset (no requester appears)
  313.  
  314.    RESULT
  315.         result - chipset flags (ROSCF_xxx, AGA includes the ECS flag) or NULL
  316.                  if required chipset not found
  317.  
  318. ros.library/ROSCPUCheck                                ros.library/ROSCPUCheck
  319.  
  320.    NAME
  321.         ROSCPUCheck -- check if desired CPU/FPU available
  322.  
  323.    SYNOPSIS
  324.         result = ROSCPUCheck(cpubit)
  325.         D0                   D0        
  326.  
  327.         UWORD ROSCPUCheck(UWORD);
  328.  
  329.    FUNCTION
  330.         Use this routine to obtain the available CPU/FPU.
  331.         As input you may specify the processor requirement (bitnumber) and if
  332.         _not_ found a requester appears to inform the user about his hardware
  333.         problem (if not suppressed and if not in Death-Mode).
  334.         Call this routine twice if you need a CPU (AFB_680x0) check and a FPU 
  335.         (AFB_6888x/FPU40) check.
  336.  
  337.    INPUTS
  338.         cpubit - the required CPU/FPU -> AttnFlags AFB_xxxxx
  339.                  or -1 for only obtaining CPU/FPU (no requester appears)
  340.  
  341.    RESULT
  342.         result - AttnFlags or NULL if required chipset not found
  343.  
  344.    NOTE
  345.         This code handles the FPU40 flag correct: it's only valid if AFB_68040
  346.         set. Keep this in mind if you examine the RESULT (AttnFlags)!!!
  347.  
  348. ros.library/ROSCPUClock                                ros.library/ROSCPUClock
  349.  
  350.    NAME
  351.         ROSCPUClock -- CPU/FPU clock calculation
  352.  
  353.    SYNOPSIS
  354.         CPU/FPUclock = ROSCPUClock()
  355.         D0  D1                          
  356.  
  357.         ULONG/ULONG ROSCPUClock(VOID);
  358.  
  359.    FUNCTION
  360.         Calculate CPU/FPU clock. The values returned should be accurate at
  361.         least 1/10 MHz, so it's enough for everyone.
  362.         This routine works with all (currently) available processors and it
  363.         takes only a few milliseconds!!!
  364.         In some cases the returned clock is NULL because of the lack of
  365.         free CIA timers (or other problems, see BUGS) so it's best to call
  366.         this routine first (e.g. before any timer function).
  367.  
  368.    RESULT
  369.         CPUclock - the CPU clock in kHz or NULL on error (see also BUGS)
  370.         FPUclock - the FPU clock in kHz or NULL on error
  371.  
  372.    NOTE
  373.         This function interrupts the Death-Mode state with ROSSysCall()!
  374.  
  375.    BUGS
  376.         In some rare cases the function returns NULL:
  377.          - on 68000/10 with only chipmem
  378.          - on _really_ slow machines (e.g. a 10MHz 68040?!?)
  379.          - on 68040/60 systems where it's impossible to turn on instruction
  380.            cache (e.g. A4000 with only chipmem and 68040.library loaded)
  381.  
  382.         The FPU clock is _always_ NULL for 68881/2 systems because I'm
  383.         (currently) unable to find a reliable algorithm (blame on me).
  384.         It's hard to deal with the asynchronous data transfer between CPU
  385.         and FPU.
  386.         On 68040/60 systems with FPU the returned value is the same like
  387.         CPU clock.
  388.  
  389. ros.library/ROSDeleteFile                            ros.library/ROSDeleteFile
  390.  
  391.    NAME
  392.         ROSDeleteFile -- Delete a file or directory
  393.  
  394.    SYNOPSIS
  395.         success = ROSDeleteFile(flags, name)
  396.         D0                      D0     A0
  397.  
  398.         ULONG ROSDeleteFile(ULONG, STRPTR);
  399.  
  400.    FUNCTION
  401.         This attempts to delete the file or directory specified by 'name'.
  402.         Note that all the files within a directory must be deleted before the
  403.         directory itself can be deleted.
  404.  
  405.         If ROSRWF_DISKWAIT flag set the routine assumes that you want to delete
  406.         'name' from a floppy. This means:
  407.          - waiting for the disk to be inserted (can't be cancelled!!!)
  408.            (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK,
  409.            NO_DISK force retry until any other error occurs)
  410.          - waiting until disk drive stopped
  411.            (implementation: polling disk.resource until drives are ready)
  412.  
  413.         Since OS2.0 it's possible to delete files from your program path
  414.         instead of the current directory using PROGDIR:xxx.
  415.         On OS1.3 the "PROGDIR:" string is automatically removed by ROS so you
  416.         don't have to worry about it. The only thing the user have to do is a
  417.         "CD" to the program directory before starting (only on OS1.3). ;-)
  418.  
  419.         WARNING: It may be dangerous to use this routine within Death-Mode!
  420.                  Because of the AMIGA's multitasking facilities it isn't
  421.                  possible (isn't it???) to wait till the final end of a delete
  422.                  operation. That's why I use a simple delay of 2 seconds after
  423.                  any delete operation in Death-Mode. If your filesystem is to
  424.                  slow to write all the data within this time your partition
  425.                  will be _not_ validated!!!
  426.                  You've been warned!!!
  427.  
  428.    INPUTS
  429.         flags - use ROSRWF_DISKWAIT if you want to delete from a floppy
  430.         name - pointer to a null-terminated string
  431.    
  432.    RESULT
  433.         success - DOS error code on failure or NULL for success
  434.  
  435.    NOTE
  436.         This function interrupts the Death-Mode state with ROSSysCall()!
  437.  
  438.    SEE ALSO
  439.         DOS.lib/DeleteFile()
  440.  
  441. ros.library/ROSDisableReq                            ros.library/ROSDisableReq
  442.  
  443.    NAME
  444.         ROSDisableReq -- suspend requesters for our task
  445.  
  446.    SYNOPSIS
  447.         ROSDisableReq()
  448.                              
  449.         VOID ROSDisableReq(VOID);
  450.  
  451.    FUNCTION
  452.         Suspend all upcoming requesters for our task (ROS- and DOS-Requesters).
  453.         By default requesters are enabled.
  454.  
  455.    SEE ALSO
  456.         ROSEnableReq(), ROSRequester()
  457.  
  458. ros.library/ROSEnableReq                              ros.library/ROSEnableReq
  459.  
  460.    NAME
  461.         ROSEnableReq -- permit requesters for our task
  462.  
  463.    SYNOPSIS
  464.         ROSEnableReq()
  465.                              
  466.         VOID ROSEnableReq(VOID);
  467.  
  468.    FUNCTION
  469.         Permit all upcoming requesters for our task (ROS- and DOS-Requesters).
  470.         By default requesters are enabled.
  471.  
  472.    SEE ALSO
  473.         ROSDisableReq(), ROSRequester()
  474.  
  475. ros.library/ROSFreeAudio                              ros.library/ROSFreeAudio
  476.  
  477.    NAME
  478.         ROSFreeAudio -- free audio channels
  479.  
  480.    SYNOPSIS
  481.         ROSFreeAudio()
  482.         
  483.         VOID ROSFreeAudio(VOID);
  484.  
  485.    FUNCTION
  486.         This function removes probably installed audio interrupt handlers and
  487.         resets the audio DMA (former system values). Then channels are freed.
  488.  
  489.         Freeing channels without allocation is harmless.
  490.    
  491.         Closing the ros.library frees audio channels automatically.
  492.  
  493.    NOTE
  494.         This function interrupts the Death-Mode state with ROSSysCall()!
  495.  
  496.    SEE ALSO
  497.         ROSAllocAudio()
  498.  
  499. ros.library/ROSFreeMem                                  ros.library/ROSFreeMem
  500.  
  501.    NAME
  502.         ROSFreeMem -- return allocated memory to the system
  503.  
  504.    SYNOPSIS
  505.         ROSFreeMem(memoryBlock)
  506.                    A0
  507.  
  508.         VOID ROSFreeMem(VOID *);
  509.  
  510.    FUNCTION
  511.         Free an allocation made by the ROSAllocMem() call. The memory will be
  512.         returned to the system pool from which it came.
  513.  
  514.         WARNING: Before freeing some chip memory be sure that the blitter has
  515.                  finished its work within this memory block!!!
  516.                  The same applies to closing the ros.library.
  517.  
  518.         Closing the ros.library frees allocated memory automatically.
  519.  
  520.    NOTE
  521.         Passing a wrong pointer is harmless ;-)
  522.  
  523.         This function interrupts the Death-Mode state with ROSSysCall()!
  524.  
  525.    INPUTS
  526.         memoryBlock - pointer to the memory block to free, or NULL
  527.  
  528.    SEE ALSO
  529.         ROSAllocMem()
  530.  
  531. ros.library/ROSGetDMA                                    ros.library/ROSGetDMA
  532.  
  533.    NAME
  534.         ROSGetDMA -- obtain DMA settings
  535.  
  536.    SYNOPSIS
  537.         DMACONR = ROSGetDMA()
  538.         D0                     
  539.  
  540.         UWORD ROSGetDMA(VOID);
  541.  
  542.    FUNCTION
  543.         This function returns current DMA settings (set via ROSSetDMA()).
  544.  
  545.         Do _not_ use "move.w $dff002,d0" !!!!!!!
  546.         This may return wrong bits if you are in Non-Death-Mode (e.g. copper
  547.         DMA -> the OS may change the bit during screen switching).
  548.         But ROSGetDMA() returns the right value.
  549.    
  550.         Closing the ros.library reset former system DMA.
  551.  
  552.    RESULT
  553.         DMACONR - DMA settings set via ROSSetDMA() with additional BBUSY/BZERO
  554.                   bits (unsupported (disk) & unallocated (audio, ...) DMA bits
  555.                   are always 0)
  556.  
  557.    NOTE
  558.         This call is guaranteed to preserve all other registers and is save
  559.         to call from interrupts.
  560.  
  561.    SEE ALSO
  562.         ROSSetDMA()
  563.  
  564. ros.library/ROSGetInt                                    ros.library/ROSGetInt
  565.  
  566.    NAME
  567.         ROSGetInt -- obtain interrupt settings
  568.  
  569.    SYNOPSIS
  570.         INTENAR = ROSGetInt()
  571.         D0                     
  572.  
  573.         UWORD ROSGetInt(VOID);
  574.  
  575.    FUNCTION
  576.         This function returns interrupt enable bits (set via ROSSetDMA()).
  577.         Additional bits are defined in "ros.i".
  578.  
  579.         Do _not_ use "move.w $dff01c,d0" !!!!!!! This may return wrong bits.
  580.    
  581.         Closing the ros.library reset former system interrupt bits.
  582.  
  583.    RESULT
  584.         INTENAR - Interrupt bits set via ROSSetInt()
  585.                   Note: level 1/2/5/6 bits (disk, serial, timer) are not
  586.                         supported!!!
  587.                         Instead additonal bits are defined:  - KEYB
  588.                                                              - CIAATIMA/B
  589.                                                              - CIABTIMA/B
  590.  
  591.    NOTE
  592.         This call is guaranteed to preserve all other registers and is save
  593.         to call from interrupts.
  594.  
  595.    SEE ALSO
  596.         ROSSetInt(), libraries/ros.i
  597.  
  598. ros.library/ROSGetKey                                    ros.library/ROSGetKey
  599.  
  600.    NAME
  601.         ROSGetKey -- returns the currently pressed rawkey code and qualifiers
  602.  
  603.    SYNOPSIS
  604.         key = ROSGetKey()
  605.         D0
  606.  
  607.         ULONG ROSGetKey(VOID);
  608.  
  609.    FUNCTION
  610.         This function returns the currently pressed non-qualifier key and
  611.         all pressed qualifiers.
  612.  
  613.         The values returned by this function are not modified by which
  614.         window/screen currently has input focus.
  615.  
  616.    RESULT
  617.         key - key code for the last non-qualifier key pressed in the low
  618.               order word ($0..$67). If no key is pressed this word will be $ff.
  619.               The upper order word contains the qualifiers which can be found
  620.               within the long word as follows (lowlevel.library like):
  621.                         Qualifier               Key
  622.                         LLKB_LSHIFT             Left Shift
  623.                         LLKB_RSHIFT             Rigt Shift
  624.                         LLKB_CAPSLOCK           Caps Lock
  625.                         LLKB_CONTROL            Control
  626.                         LLKB_LALT               Left Alt
  627.                         LLKB_RALT               Right Alt
  628.                         LLKB_LAMIGA             Left Amiga
  629.                         LLKB_RAMIGA             Right Amiga    
  630.  
  631.    NOTE
  632.         This call is guaranteed to preserve all other registers and is save
  633.         to call from interrupts.
  634.  
  635.    SEE ALSO
  636.         lowlevel.lib/GetKey(), libraries/lowlevel.i
  637.  
  638. ros.library/ROSKillSystem                            ros.library/ROSKillSystem
  639.  
  640.    NAME
  641.         ROSKillSystem -- kill the system and open a PAL-LowRes screen
  642.  
  643.    SYNOPSIS
  644.         success = ROSKillSystem(mode)
  645.         D0                      D0
  646.  
  647.         BOOL ROSKillSystem(ULONG);
  648.  
  649.    FUNCTION
  650.         This function opens a PAL-LowRes screen, installs your copper list and
  651.         sets additional DMA (copper, bitplane, sprite).
  652.         By default all DMA will be cleared.
  653.         Whenever this screen is the frontmost you may bash all display related
  654.         custom chip registers (preferably via copper list).
  655.         If the ROS is unable to open the screen or if it's not PAL-LowRes
  656.         (promoted screen) a Retry/Cancel-Requester appears (if not suppressed).
  657.  
  658.         If you specify the flag KILLF_DEATHMODE the multitasking will be turned
  659.         off. Now ROS has taken over the entire system. But interrupts and DMA
  660.         should only be set with ROS functions!!!
  661.         The blitter is owned via OwnBlitter() so you may use it. But before
  662.         using you should do a WaitBlit because it may still working.
  663.         You may interrupt the Death-Mode via ROSSysCall(). At this time the
  664.         blitter will be disowned so you do _not_ use it during a SysCall!!!
  665.  
  666.         Call ROSKillSystem() with KILLF_SYSMODE to run your application within
  667.         multitasking. But be polite and bash the hardware as less as possible.
  668.         The blitter is under system control so you should use OwnBlitter()/
  669.         DisownBlitter() if you need it. But allocate the blitter only for a
  670.         short time because the system uses it too!
  671.  
  672.         Also check out the ROS_KillSysFlags (the current ROS state).
  673.         You may call ROSKillSystem() multiple times to switch between Death- 
  674.         and SysMode.
  675.         A switch from Sys- into Death-Mode automatically makes the ROS screen 
  676.         the frontmost so you don't have to call ROSScreenToFront().
  677.  
  678.         You should return to the system with ROSAwakeSystem().
  679.         Closing the ros.library calls ROSAwakeSystem() automatically.
  680.  
  681.    INPUTS
  682.         mode - KILLF_SYSMODE for a multitasking environment
  683.                KILLF_DEATHMODE to take over the entire system
  684.  
  685.    RESULT
  686.         success - FALSE if ROS was unable to open the screen
  687.  
  688.    SEE ALSO
  689.         ROSAwakeSystem(), ROSSysCall(), ROSSysCallEnd()
  690.  
  691. ros.library/ROSQueryKeys                              ros.library/ROSQueryKeys
  692.  
  693.    NAME
  694.         ROSQueryKeys -- return the states for a set of keys
  695.  
  696.    SYNOPSIS
  697.         ROSQueryKeys(queryArray, arraySize)
  698.                      A0          D0
  699.  
  700.         VOID ROSQueryKeys(struct KeyQuery *, UBYTE);
  701.  
  702.    FUNCTION
  703.         Scans the keyboard to determine which of the rawkey codes
  704.         listed in the 'queryArray' are currently pressed. The state for each
  705.         key is returned in the array.
  706.  
  707.         The values returned by this function are not modified by which
  708.         window/screen currently has input focus.
  709.  
  710.    INPUTS
  711.         queryArray - an array of KeyQuery structures. The kq_KeyCode fields
  712.                      of these structures should be filled with the rawkey
  713.                      codes you wish to query about. Upon return from this
  714.                      function, the kq_Pressed field of these structures
  715.                      will be set to TRUE if the associated key is down,
  716.                      and FALSE if not.
  717.         arraySize - number of key code entries in 'queryArray'
  718.  
  719.    NOTE
  720.         This function is save to call from interrupts.
  721.  
  722.    SEE ALSO
  723.         lowlevel.lib/QueryKeys(), libraries/lowlevel.i
  724.  
  725. ros.library/ROSReadExe                                  ros.library/ROSReadExe
  726.  
  727.    NAME
  728.         ROSReadExe -- scatterload a loadable file
  729.  
  730.    SYNOPSIS
  731.         seglist/errorcode = ROSReadExe(flags, name)
  732.         D0      D1                     D0     A0
  733.  
  734.         BPTR/ULONG ROSReadExe(ULONG, STRPTR);
  735.  
  736.    FUNCTION
  737.         This function tries to scatterload the file 'name' using DOS.library's
  738.         LoadSeg().
  739.  
  740.         If ROSRWF_DISKWAIT flag set the routine assumes that you want to load
  741.         'name' from a floppy. This means:
  742.          - waiting for the disk to be inserted (can't be cancelled!!!)
  743.            (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK,
  744.            NO_DISK force retry until any other error occurs)
  745.          - waiting until disk drive stopped
  746.            (implementation: polling disk.resource until drives are ready)
  747.  
  748.         Since OS2.0 it's possible to load files from your program path instead
  749.         of the current directory using PROGDIR:xxx.
  750.         On OS1.3 the "PROGDIR:" string is automatically removed by ROS so you
  751.         don't have to worry about it. The only thing the user have to do is a
  752.         "CD" to the program directory before starting (only on OS1.3). ;-)
  753.  
  754.         You should unload the file with ROSFreeMem(seglist)!
  755.         Do _not_ use DOS.library's UnLoadSeg()!!!!!!!
  756.         Closing the ros.library unloads file automatically.
  757.  
  758.    INPUTS
  759.         flags - use ROSRWF_DISKWAIT if you want to load from a floppy
  760.         name - pointer to a null-terminated string
  761.    
  762.    RESULT
  763.         seglist - BCPL pointer to a seglist or NULL if error
  764.         errorcode - DOS error code on failure (may be NULL!!!)
  765.  
  766.    NOTE
  767.         This function interrupts the Death-Mode state with ROSSysCall()!
  768.  
  769.    SEE ALSO
  770.         ROSFreeMem(), DOS.lib/LoadSeg()
  771.  
  772. ros.library/ROSReadFile                                ros.library/ROSReadFile
  773.  
  774.    NAME
  775.         ROSReadFile -- read a number bytes from a file
  776.  
  777.    SYNOPSIS
  778.         actLength/errorcode/actBuffer = ROSReadFile(flags, length, offset,
  779.         D0        D1        A0                      D0     D1      D2      
  780.                                                memtype, memalign, name, buffer)
  781.                                                D3       D4        A0    A1
  782.  
  783.         ULONG/ULONG/VOID *  ROSReadFile(ULONG, ULONG, ULONG,
  784.                                                  ULONG, ULONG, STRPTR, VOID *);
  785.  
  786.    FUNCTION
  787.         This function tries to load 'length' bytes from the file 'name' using
  788.         DOS.library's Read(). Set 'length` = 0 to load the whole file.
  789.         A1 points to a buffer where the data should be placed, or set A1=0 
  790.         to force an automatic memory allocation. In this case you must specify
  791.         'memtype' and 'memalign' (see also ROSAllocMem()).
  792.       
  793.         If ROSRWF_DISKWAIT flag set the routine assumes that you want to load
  794.         'name' from a floppy. This means:
  795.          - waiting for the disk to be inserted (can't be cancelled!!!)
  796.            (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK,
  797.            NO_DISK force retry until any other error occurs)
  798.          - waiting until disk drive stopped
  799.            (implementation: polling disk.resource until drives are ready)
  800.  
  801.         Since OS2.0 it's possible to load files from your program path instead
  802.         of the current directory using PROGDIR:xxx.
  803.         On OS1.3 the "PROGDIR:" string is automatically removed by ROS so you
  804.         don't have to worry about it. The only thing the user have to do is a
  805.         "CD" to the program directory before starting (only on OS1.3). ;-)
  806.  
  807.         You should free the automatically allocated memory with ROSFreeMem()!
  808.         Closing the ros.library unloads file automatically (if automatic
  809.         memory allocation).
  810.  
  811.    INPUTS
  812.         flags - use ROSRWF_DISKWAIT if you want to load from a floppy
  813.         length - number of bytes to load or NULL for the whole file
  814.         offset - number of bytes to skip before reading from file
  815.         memtype - see ROSAllocMem(), only neccessary if 'buffer' == NULL
  816.         memalign - see ROSAllocMem(), only neccessary if 'buffer' == NULL
  817.         name - pointer to a null-terminated string
  818.         buffer - pointer to buffer or NULL to force an automitic memory
  819.                  allocation
  820.    
  821.    RESULT
  822.         actLength - number of bytes read from file or -1 if error
  823.         errorcode - DOS error code on failure (may be NULL!!!)
  824.         actBuffer - points to loaded data, only valid on success (D0 <> -1)!!!
  825.  
  826.    NOTE
  827.         This function interrupts the Death-Mode state with ROSSysCall()!
  828.  
  829.    SEE ALSO
  830.         ROSAllocMem(), ROSFreeMem(), DOS.lib/Read()
  831.  
  832. ros.library/ROSRemTimerInt                          ros.library/ROSRemTimerInt
  833.  
  834.    NAME
  835.         ROSRemTimerInt -- remove a previously installed timer interrupt
  836.  
  837.    SYNOPSIS
  838.         ROSRemTimerInt(intHandle);
  839.                        A1
  840.  
  841.         VOID AddTimerInt(ULONG);
  842.  
  843.    FUNCTION
  844.         Removes a timer interrupt routine previously installed with
  845.         ROSAddTimerInt().
  846.  
  847.         Closing the ros.library removes this timer interrupt automatically.
  848.  
  849.    INPUTS
  850.         intHandle - handle obtained from ROSAddTimerInt(), if NULL nothing
  851.                     happens
  852.  
  853.    NOTE
  854.         This function interrupts the Death-Mode state with ROSSysCall()!
  855.  
  856.    SEE ALSO
  857.         ROSAddTimerInt(), ROSStartTimer(), ROSStopTimer(), ROSSetTimerVec()
  858.  
  859. ros.library/ROSRequester                              ros.library/ROSRequester
  860.  
  861.     NAME
  862.         ROSRequester -- Display a requester
  863.  
  864.     SYNOPSIS
  865.         result = ROSRequester(TextFormat, ArgList, GadgetFormat)
  866.         D0                    A0          A1       A2
  867.  
  868.         LONG ROSRequester(STRPTR, APTR, STRPTR)
  869.  
  870.     FUNCTION
  871.         This procedure automatically builds a requester for you using
  872.         intuition's EasyRequestArgs() (AutoRequest() on OS1.3) and then
  873.         waits for a response from the user.
  874.  
  875.         The requester appears only if it is not disabled via ROSDisableReq()
  876.         or your tasks pr_WindowPtr = -1.
  877.         Do not set this pointer directly. Use instead ROSDisable()/ROSEnable().
  878.         By default requesters are enabled.
  879.  
  880.         In Death-Mode requesters are always disabled.
  881.         If requesters are disabled the 'result' will be always FALSE (NULL).
  882.  
  883.     INPUTS
  884.         TextFormat - Format string, a la RawDoFmt(), for message in
  885.             requester body. Lines are separated by the newline character ($0A).
  886.             Formatting '%' functions are supported exactly as in RawDoFmt().
  887.             Note: on OS1.3 max 5 textlines
  888.         GadgetFormat - Format string for gadgets.  Text for separate
  889.             gadgets is separated by '|'. You MUST specify at least one gadget.
  890.             Note: max 2 gadgets on OS1.3
  891.                   gadget format functions only supported on OS2.0+.
  892.         argList - Arguments for format commands. Arguments for gadgets
  893.                   follow arguments for bodytext
  894.  
  895.     RESULT
  896.         0, 1, ..., N - Successive GadgetID values, for the gadgets
  897.                        you specify for the requester.  NOTE: The numbering
  898.                        from left to right is actually: 1, 2, ..., N, 0.
  899.                        This is for compatibility with AutoRequest(), which has
  900.                        FALSE for the rightmost gadget. 
  901.  
  902.     BUGS
  903.         Do not rely on the 'result' of an one-button requester!
  904.         Due a bug in intuitions AutoRequest()/EasyRequestArgs() the 'result'
  905.         may be TRUE (1) or FALSE (0) because it's possible to satisfy an one-
  906.         button requester with both short-cuts: AMIGA-B and AMIGA-V.
  907.  
  908.     SEE ALSO
  909.         intuition.lib/AutoRequest(), intuition.lib/EasyRequestArgs(),
  910.         exec.lib/RawDoFmt(), ROSDisableReq(), ROSEnableReq()
  911.  
  912. ros.library/ROSScreenToBack                        ros.library/ROSScreenToBack
  913.  
  914.     NAME
  915.         ROSScreenToBack -- Send ROS screen to the back of the display
  916.  
  917.     SYNOPSIS
  918.         ROSScreenToBack()
  919.  
  920.         VOID ROSScreenToBack(VOID);
  921.  
  922.     FUNCTION
  923.         Sends the ROS screen to the back of the display if it is open and
  924.         if _not_ in Death-Mode.
  925.  
  926.     SEE ALSO
  927.         ROSScreenToFront()
  928.  
  929. ros.library/ROSScreenToFront                      ros.library/ROSScreenToFront
  930.  
  931.     NAME
  932.         ROSScreenToFront -- Make ROS screen the frontmost
  933.  
  934.     SYNOPSIS
  935.         ROSScreenToFront()
  936.  
  937.         VOID ROSScreenToFront(VOID);
  938.  
  939.     FUNCTION
  940.         Brings the ROS screen to the front of the display if it is open and
  941.         if _not_ in Death-Mode.
  942.  
  943.     SEE ALSO
  944.         ROSScreenToBack()
  945.  
  946. ros.library/ROSSetCache                                ros.library/ROSSetCache
  947.  
  948.    NAME
  949.         ROSSetCache - Instruction & data cache control
  950.  
  951.    SYNOPSIS
  952.         oldBits = ROSSetCache(cacheBits, cacheMask)
  953.         D0                    D0         D1
  954.  
  955.         ULONG ROSSetCache(ULONG, ULONG);
  956.  
  957.    FUNCTION
  958.         This function provides global control of any instruction or data
  959.         caches that may be connected to the system.  All settings are
  960.         global (until ros.library closed) -- per task control is not provided.
  961.  
  962.         Closing the ros.library reset former system cache settings.
  963.  
  964.    INPUTS
  965.         cacheBits - new values for the bits specified in cacheMask.
  966.                     use -1 to reset to system defaults (ignores cacheMask)
  967.         cacheMask - a mask with ones for all bits to be changed
  968.  
  969.         Note: cacheBits/cacheMask may be overridden by values specified in
  970.               ROS.prefs (to support individual cache settings)
  971.  
  972.    RESULT
  973.         oldBits - the complete prior values for all settings.
  974.  
  975.    NOTE
  976.         As a side effect, this function clears all caches.
  977.         This function interrupts the Death-Mode state with ROSSysCall()!
  978.  
  979.    SEE ALSO
  980.         exec/execbase.i, exec.lib/CacheControl()
  981.  
  982. ros.library/ROSSetCopper                              ros.library/ROSSetCopper
  983.  
  984.    NAME
  985.         ROSSetCopper -- install copperlist for ROS screen
  986.  
  987.    SYNOPSIS
  988.         ROSSetCopper(flags, coplist)
  989.                      D0     A0   
  990.  
  991.         VOID ROSSetCopper(ULONG, APTR);
  992.  
  993.    FUNCTION
  994.         This function installs a new copper list for our ROS screen.
  995.         Whenever this screen is the frontmost this copper list becomes the
  996.         active.
  997.  
  998.         Do _not_ use "move.l #mycoplist,$dff080" or "move.w #0,$dff088" !!!!!!!
  999.         This may crash the display if you are in Non-Death-Mode and the ROS
  1000.         screen is not yet available or behind others.
  1001.         ROSSetCopper() takes this into account and displays this copper list as
  1002.         soon as possible.
  1003.         
  1004.         A screen switch forces always copper1 starting in a long frame!
  1005.  
  1006.    INPUTS
  1007.         flags - COPF_COPPER1/2: modify copper1 or copper2
  1008.                     Remember: copper1 is always started during vertical blank
  1009.                 COPF_STROBE: force an immediate copper start, move.w #0,$dff088
  1010.                     set 'coplist' to NULL for only strobe 
  1011.                 COPF_LOF/SHF: forces a long/short frame while starting copper
  1012.                     (to display interlaced screens correctly)
  1013.         coplist - copper list pointer, if NULL the old copper pointer remains
  1014.  
  1015.    NOTE
  1016.         This call is guaranteed to preserve all registers (except D0!!!) and is
  1017.         save to call from interrupts.
  1018.  
  1019.    SEE ALSO
  1020.         libraries/ros.i, ROSKillSystem()
  1021.  
  1022.  
  1023. ros.library/ROSSetDMA                                    ros.library/ROSSetDMA
  1024.  
  1025.    NAME
  1026.         ROSSetDMA -- modify DMA bits
  1027.  
  1028.    SYNOPSIS
  1029.         ROSSetDMA(DMACON)
  1030.                   D0                     
  1031.  
  1032.         ROSSetDMA(UWORD);
  1033.  
  1034.    FUNCTION
  1035.         This function acts like a write to the DMACON register.
  1036.  
  1037.         Do _not_ use "move.w #xxx,$dff096" !!!!!!!
  1038.         This may interfere with the system you are in Non-Death-Mode, but
  1039.         ROSSetDMA() handles all exceptions correctly.
  1040.         
  1041.         DMA bit modification:
  1042.           - DMAF_BLTPRI: only in Death-Mode, but during a ROSSysCall() the
  1043.                          system DMA bit will be restored
  1044.           - DMAF_DMAEN: same like BLTPRI
  1045.           - DMAF_BPLEN: only if ROS screen in front
  1046.           - DMAF_COPEN: same like BPLEN
  1047.           - DMAF_BLTEN: same like BLTPRI
  1048.           - DMAF_SPREN: same like BPLEN
  1049.           - DMAF_DSKEN: never modified!!!
  1050.           - DMAF_AUDxEN: only if audio channels allocated
  1051.  
  1052.         A currently forbidden DMA modification is automatically updated as
  1053.         soon as possible (e.g. bitplane DMA if ROS screen behind others).
  1054.  
  1055.         Closing the ros.library reset former system DMA.
  1056.  
  1057.    INPUTS
  1058.         DMACON - DMA bits
  1059.  
  1060.    NOTE
  1061.         This call is guaranteed to preserve all registers (except D0!!!) and is
  1062.         save to call from interrupts.
  1063.  
  1064.    SEE ALSO
  1065.         ROSGetDMA(), hardware/dmabits.i
  1066.  
  1067. ros.library/ROSSetExitHandler                    ros.library/ROSSetExitHandler
  1068.  
  1069.    NAME
  1070.         ROSSetExitHandler -- add handler that is executed at exit key condition
  1071.  
  1072.    SYNOPSIS
  1073.         ROSSetExitHandler(handler);
  1074.                           A0
  1075.  
  1076.         ROSSetExitHandler(APTR);
  1077.  
  1078.    FUNCTION
  1079.         Calling this routine causes the ROS to install an exit key conditon
  1080.         handler. Whenever this special key is pressed your handler is invoked
  1081.         (should be only once). Now it's time to finish your application. 
  1082.  
  1083.         The routine is called from within an interrupt, so normal
  1084.         restrictions apply. On entry A5 holds the custom base ($dff000) and
  1085.         A6 holds _ROSBase. Your code may trash all registers.
  1086.  
  1087.         The default exit key code is SHIFT ESC but may be changed in ROS.prefs.
  1088.  
  1089.         You should remove this handler with ROSSetExitHandler(NULL).
  1090.         Closing the ros.library removes this timer interrupt automatically.
  1091.  
  1092.    INPUTS
  1093.         handler - the routine to invoke upon exit key condition or NULL to
  1094.                   detach the handler
  1095.  
  1096.    NOTE
  1097.         This call is guaranteed to preserve all registers (except A0!!!) and is
  1098.         save to call from interrupts.
  1099.  
  1100.         The handler may be called more than once if your application isn't 
  1101.         fast enough to exit!!!
  1102.  
  1103.    SEE ALSO
  1104.  
  1105. ros.library/ROSSetInt                                    ros.library/ROSSetInt
  1106.  
  1107.    NAME
  1108.         ROSSetInt -- modify interrupt settings
  1109.  
  1110.    SYNOPSIS
  1111.         ROSSetInt(INTENA)
  1112.                   D0                     
  1113.  
  1114.         ROSSetInt(UWORD);
  1115.  
  1116.    FUNCTION
  1117.         This function acts like a write to the INTENA register.
  1118.  
  1119.         Do _not_ use "move.w #xxx,$dff09a" !!!!!!!
  1120.         This may interfere with the system you are in Non-Death-Mode, but
  1121.         ROSSetInt() handles all exceptions correctly.
  1122.  
  1123.         Only those bits are affected which belongs to previous ROSSetIntVec()
  1124.         calls. Look at ROSSetIntVec() for further information.
  1125.         
  1126.         In Non-Death-Mode the master interrupt bit (INTB_INTEN) is emulated to
  1127.         support enable/disable of all ROS interrupts at once (system interrupts
  1128.         are still active!!!)
  1129.         
  1130.         Closing the ros.library reset former system interrupt bits.
  1131.  
  1132.    INPUTS
  1133.         INTENA - Int bits
  1134.                  Note: level 1/2/5/6 bits (disk, serial, timer) are not
  1135.                        supported!!!
  1136.                        Instead additonal bits are defined:  - KEYB
  1137.                                                             - CIAATIMA/B
  1138.                                                             - CIABTIMA/B
  1139.                  Look at ROSSetIntVec() for further details
  1140.    NOTE
  1141.         This call is guaranteed to preserve all registers (except D0!!!).
  1142.  
  1143.         Do _not_ call this routine from interrupts if you want to modify the
  1144.         CIA interrupts (CIAATIMA/B, CIABTIMA/B)!!!!
  1145.  
  1146.    SEE ALSO
  1147.         ROSGetInt(), ROSSetIntVec(), libraries/ros.i
  1148.  
  1149. ros.library/ROSSetIntVec                              ros.library/ROSSetIntVec
  1150.  
  1151.    NAME
  1152.         ROSSetIntVec -- set a new handler for an interrupt vector
  1153.  
  1154.    SYNOPSIS
  1155.         success = ROSSetIntVec(intNum, handler)
  1156.         D0                     D0      A0               
  1157.  
  1158.         BOOL ROSSetIntVec(UWORD, APTR);
  1159.  
  1160.    FUNCTION
  1161.         This function attaches a new handler to the interrupt specified with
  1162.         'intNum'. Detach a handler with A0 = NULL.
  1163.         The routine is called from within an interrupt, so normal
  1164.         restrictions apply. On entry A5 holds the custom base ($dff000) and
  1165.         A6 holds _ROSBase. Your code may trash all registers.
  1166.         Your handler won't be invoked until you enable it (and the master int)
  1167.         via ROSSetInt(). After enabling your handler it's always invoked
  1168.         whether you taken over the systen or not.
  1169.  
  1170.         Interrupts are executed as follows:
  1171.  
  1172.         » INTB_BLIT
  1173.             - only in Death-Mode, during a ROSSysCall() the system routine
  1174.               will be restored so you do _not_ use the blitter while the system
  1175.               is (partially) active
  1176.             - returncode is always TRUE
  1177.         » INTB_VERTB
  1178.             - always invoked, also without a call to ROSKillSystem()
  1179.             - in Non-Death-Mode your vblank code may be called after display
  1180.               is started depending on the speed of higher prioritized vblank
  1181.               interrupts. If you want to synchronize custom chip modifications
  1182.               with the display you should use the copper.
  1183.             - but remember: in Non-Death-Mode the vblank frequency may vary
  1184.               (not always 50Hz) if ROS screen behind others!
  1185.             - returncode is always TRUE
  1186.         » INTB_COPER
  1187.             - only if ROS screen in front
  1188.             - returncode is always TRUE
  1189.         » INTB_NMI (bit 15)
  1190.             - always invoked
  1191.             - returncode is always TRUE
  1192.         » INTB_AUD0..3
  1193.             - only if channels allocated, else the returncode will be FALSE
  1194.  
  1195.         Further 5 new int definitions are supported:
  1196.  
  1197.         » INTB_CIAATIMA/CIAATIMB/CIABTIMA/CIABTIMB
  1198.             - used to attach a handler to the specified CIA timer
  1199.             - returncode may be FALSE if CIA allocation failed, in this case a
  1200.               Retry/Cancel-Requester appears (if not suppressed)
  1201.             - if returncode TRUE the specified timer bits are set to 0 (timer
  1202.               stopped) and now you may modify the contents of the CIA control
  1203.               register (CRA/CRB)
  1204.             - never read or write the CIA interrupt control register (ICR),
  1205.               use instead ROSSetInt() to enable/disble CIA interrupts!!!!!!
  1206.  
  1207.         » INTB_KEYB
  1208.             - used to track keyboard events (see also ROSGetKey())
  1209.             - only invoked if ROS screen in front!!!
  1210.             - your handler is called with additional register D0 setup:
  1211.                 * the lower word contains the keycode ($0..$67) with the
  1212.                   additional key_up/down flag (bit7 set for key-up condition)
  1213.                 * the upper word contains the qualifier bits (shift, alt, ...)
  1214.             - in Non-Death-Mode it's up to you passing this key to other system
  1215.               components (like intuition.lib, commodities.lib, ...)
  1216.                 * set the ZERO-flag at the end of your handler to pass the key
  1217.                   to other system components, e.g.  moveq #0,d0
  1218.                 * else clear the ZERO-flag, e.g.  moveq #1,d0
  1219.                 * but remember: if you catch all key events screen switching
  1220.                   and other system hotkeys dosn't work!!!
  1221.                 * by default all keys without left-amiga or without control
  1222.                   qualifiers are catched to prevent background menu activities
  1223.                   and other undesirable things
  1224.             - returncode is always TRUE
  1225.  
  1226.         All other interrupt bits are _not_ supported!!!
  1227.  
  1228.         Closing the ros.library detaches interrupt handlers automatically.
  1229.  
  1230.    INPUTS
  1231.         intnum - the Paula interrupt bit number (0 through 14). Processor
  1232.                  level seven interrupts (NMI) are encoded as intNum 15.
  1233.                  Note: level 1/2/5/6 bits (disk, serial, timer) are not
  1234.                        supported!!!
  1235.                        Instead additonal bits are defined:  - KEYB
  1236.                                                             - CIAATIMA/B
  1237.                                                             - CIABTIMA/B
  1238.         handler - the routine to invoke or NULL to detach the handler
  1239.  
  1240.    RESULT
  1241.         success - TRUE if handler successfully attached
  1242.  
  1243.    NOTE
  1244.         This call is guaranteed to preserve all other registers.
  1245.  
  1246.         Do _not_ call this routine from interrupts if you want to add a CIA
  1247.         handler for the first time!!! After a successful call you may change
  1248.         this vector with ROSSetIntVec() also from interrupts because the
  1249.         desired CIA is already allocated.
  1250.  
  1251.    SEE ALSO
  1252.         ROSSetInt(), ROSGetInt(), libraries/ros.i
  1253.  
  1254. ros.library/ROSSetTimerVec                          ros.library/ROSSetTimerVec
  1255.  
  1256.    NAME
  1257.         ROSSetTimerVec -- change the timer interrupt entry point
  1258.  
  1259.    SYNOPSIS
  1260.         ROSSetTimerVec(intRoutine, intHandle);
  1261.                        A0          A1
  1262.  
  1263.         VOID ROSSetTimerVec(APTR, ULONG);
  1264.  
  1265.    FUNCTION
  1266.         This routine changes the interrupt entry point that is assocatied with
  1267.         a timer interrupt created by ROSAddTimerInt().
  1268.         No timer modification is done (no restart, no stop). The next interrupt
  1269.         will execute your new 'intRoutine'.
  1270.  
  1271.    INPUTS
  1272.         intRoutine - the routine to invoke upon timer interrupts.
  1273.         intHandle - handle obtained from ROSAddTimerInt().
  1274.  
  1275.    NOTE
  1276.         This call is guaranteed to preserve all registers (except A1!!!) and is
  1277.         save to call from interrupts.
  1278.  
  1279.    SEE ALSO
  1280.         ROSAddTimerInt(), ROSRemTimerInt(), ROSStartTimer(), ROSStopTimer()
  1281.  
  1282. ros.library/ROSStartTimer                            ros.library/ROSStartTimer
  1283.  
  1284.    NAME
  1285.         ROSStartTimer -- start the timer associated with the timer interrupt
  1286.  
  1287.    SYNOPSIS
  1288.         ROSStartTimer(timeInterval, continuous, intHandle);
  1289.                       D0            D1          A1
  1290.  
  1291.         VOID ROSStartTimer(ULONG, BOOL, ULONG);
  1292.  
  1293.    FUNCTION
  1294.         This routine starts a stopped timer that is assocatied with a
  1295.         timer interrupt created by ROSAddTimerInt().
  1296.  
  1297.    INPUTS
  1298.         timeInterval - number of micoseconds between interrupts. The
  1299.                        maximum value allowed is 90,000. If higher values
  1300.                        are passed there will be unexpected results.
  1301.         continuous - FALSE for a one shot interrupt. TRUE for multiple
  1302.                      interrupts.
  1303.         intHandle - handle obtained from ROSAddTimerInt().
  1304.  
  1305.    NOTE
  1306.         This call is guaranteed to preserve register A0 and is save to call
  1307.         from interrupts.
  1308.  
  1309.    SEE ALSO
  1310.         ROSAddTimerInt(), ROSRemTimerInt(), ROSSetTimerVec(), ROSStopTimer()
  1311.  
  1312. ros.library/ROSStopTimer                              ros.library/ROSStopTimer
  1313.  
  1314.    NAME
  1315.         ROSStopTimer -- stop the timer associated with the timer interrupt
  1316.  
  1317.    SYNOPSIS
  1318.         ROSStopTimer(intHandle);
  1319.                      A1
  1320.  
  1321.         VOID ROSStopTimer(ULONG);
  1322.  
  1323.    FUNCTION
  1324.         Stops the timer associated with the timer interrupt handle passed.
  1325.         This is used to stop a continuous timer started by
  1326.         ROSStartTimer().
  1327.  
  1328.    INPUTS
  1329.         intHandle - handle obtained from ROSAddTimerInt()
  1330.  
  1331.    NOTE
  1332.         This call is guaranteed to preserve all registers (except A1!!!) and is
  1333.         save to call from interrupts.
  1334.  
  1335.    SEE ALSO
  1336.         ROSAddTimerInt(), ROSRemTimerInt(), ROSSetTimerVec(), ROSStartTimer()
  1337.  
  1338. ros.library/ROSSysCall                                  ros.library/ROSSysCall
  1339.  
  1340.    NAME
  1341.         ROSSysCall -- interrupts Death-Mode to enable system calls
  1342.  
  1343.    SYNOPSIS
  1344.         ROSSysCall()
  1345.  
  1346.         VOID ROSSysCall(VOID)
  1347.  
  1348.    FUNCTION
  1349.         This function provides a method to call system functions from within
  1350.         Death-Mode.
  1351.  
  1352.         YOU SHOULD NEVER NEED THIS FUNCTION! IT SHOULD BE A PRIVATE ROS CALL.
  1353.         DO NOT USE THIS CALL WITHOUT GOOD JUSTIFICATION.
  1354.  
  1355.         In order to restore normal Death-Mode, the programmer must execute
  1356.         exactly one call to ROSSysCallEnd() for every call to ROSSysCall().
  1357.  
  1358.         During a SysCall all ROS interrupts continue executing (look at
  1359.         ROSSetIntVec() for details).
  1360.         But remember: system interrupts are also active and additional system
  1361.         DMA will be set!
  1362.         The blitter will be disowned so you do _not_ bash the blitter until
  1363.         ROSSysCallEnd() is called.
  1364.         Do _not_ call system functions during a SysCall which may cause any
  1365.         visual modifications (like OpenScreen(), ScreenToBack(), ...).
  1366.         These functions will never return as long as the Death-Mode is the
  1367.         active one!!!
  1368.  
  1369.         Calling ROSSysCall() without a Death-Mode killed system is harmless.
  1370.  
  1371.    RESULT
  1372.         A partially active system.
  1373.  
  1374.    NOTE
  1375.         This call is guaranteed to preserve all registers.
  1376.  
  1377.    SEE ALSO
  1378.         ROSKillSystem(), ROSSetDMA(), ROSSetIntVec(), ROSSysCallEnd()
  1379.  
  1380. ros.library/ROSSysCallEnd                            ros.library/ROSSysCallEnd
  1381.  
  1382.    NAME
  1383.         ROSSysCallEnd -- return from a SysCall
  1384.  
  1385.    SYNOPSIS
  1386.         ROSSysCallEnd()
  1387.  
  1388.         VOID ROSSysCallEnd(VOID)
  1389.  
  1390.    FUNCTION
  1391.         Call this function to return from a SysCall after a matching
  1392.         ROSSysCall() has been executed.
  1393.  
  1394.    RESULT
  1395.         A Death-Mode killed system.
  1396.  
  1397.    NOTE
  1398.         This call is guaranteed to preserve all registers.
  1399.  
  1400.    SEE ALSO
  1401.         ROSSysCall()
  1402.  
  1403. ros.library/ROSWaitVBlank                            ros.library/ROSWaitVBlank
  1404.  
  1405.    NAME
  1406.        ROSWaitVBlank -- Wait for the vertical blank to occur
  1407.        
  1408.    SYNOPSIS
  1409.        ROSWaitVBlank()
  1410.  
  1411.        VOID ROSWaitVBlank(VOID);
  1412.  
  1413.    FUNCTION
  1414.        Waits for vertical blank to occur and than returns to the caller.
  1415.  
  1416.    NOTE
  1417.         This call is guaranteed to preserve all registers and is save to call
  1418.         from interrupts.
  1419.         This call does not require A6 to be loaded with the library base.
  1420.  
  1421.    BUGS
  1422.        Currently this routine polls the VPOSR register so you should only use
  1423.        this call if the ROS screen is the frontmost.
  1424.        It doesn't work while displaying a 'foreign' screen on a graphics board.
  1425.  
  1426. ros.library/ROSWriteFile                              ros.library/ROSWriteFile
  1427.  
  1428.    NAME
  1429.         ROSWriteFile -- Write a number bytes to a file
  1430.  
  1431.    SYNOPSIS
  1432.         actLength/errorcode = ROSWriteFile(flags, length, offset, name, buffer)
  1433.         D0        D1                       D0     D1      D2      A0    A1
  1434.  
  1435.         ULONG/ULONG ROSWriteFile(ULONG, ULONG, ULONG, STRPTR, VOID *);
  1436.  
  1437.    FUNCTION
  1438.         This function writes 'length' bytes to the file 'name' using
  1439.         DOS.library's Write(). 
  1440.         Set 'offset' to NULL to overwrite an existing file (file opened with
  1441.         MODE_NEWFILE). In the other case the data is written to the file 'name'
  1442.         with an 'offset' from the beginning (file opened with MODE_READWRITE).
  1443.         This can be used to append/replace data to/in an existing file. If the
  1444.         file doesn't exists or if filelength shorter than 'offset' a seek error
  1445.         occurs.
  1446.         A1 points to a buffer from where the data is taken from. 
  1447.  
  1448.         Remember: On error a corrupt or a 0-byte-file may still exists!!!
  1449.                   It's up to you to delete this.
  1450.  
  1451.         If ROSRWF_DISKWAIT flag set the routine assumes that you want to write
  1452.         'name' to a floppy. This means:
  1453.          - waiting for the disk to be inserted (can't be cancelled!!!)
  1454.            (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK,
  1455.            NO_DISK force retry until any other error occurs)
  1456.          - waiting until disk drive stopped
  1457.            (implementation: polling disk.resource until drives are ready)
  1458.  
  1459.         Since OS2.0 it's possible to write files to your program path instead
  1460.         of the current directory using PROGDIR:xxx.
  1461.         On OS1.3 the "PROGDIR:" string is automatically removed by ROS so you
  1462.         don't have to worry about it. The only thing the user have to do is a
  1463.         "CD" to the program directory before starting (only on OS1.3). ;-)
  1464.  
  1465.         WARNING: It may be dangerous to use this routine within Death-Mode!
  1466.                  Because of the AMIGA's multitasking facilities it isn't
  1467.                  possible (isn't it???) to wait till the final end of a write
  1468.                  operation. That's why I use a simple delay of 2 seconds after
  1469.                  any write operation in Death-Mode. If your filesystem is to 
  1470.                  slow to write all the data within this time your partition
  1471.                  will be _not_ validated!!!
  1472.                  You've been warned!!!
  1473.  
  1474.    INPUTS
  1475.         flags - use ROSRWF_DISKWAIT if you want to write to a floppy
  1476.         length - number of bytes to write
  1477.         offset - NULL for overwrite mode, else a number of bytes to skip
  1478.                  before writing into an existing file
  1479.         name - pointer to a null-terminated string
  1480.         buffer - pointer to buffer where data is taken from
  1481.    
  1482.    RESULT
  1483.         actLength - number of bytes written or -1 if error
  1484.         errorcode - DOS error code on failure (may be NULL!!!)
  1485.  
  1486.    NOTE
  1487.         This function interrupts the Death-Mode state with ROSSysCall()!
  1488.  
  1489.    SEE ALSO
  1490.         DOS.lib/Write(), ROSDeleteFile()
  1491.  
  1492.  
  1493.